JDBC query execution can indefinitely block the calling thread when a statement is executed or a resultset is being iterated. In some situations you may wish to have your calling threads held in these blocked states. When using embedded connections, you may optionally use the org.teiid.jdbc.TeiidStatement and org.teiid.jdbc.TeiidPreparedStatement interfaces to execute queries with a callback org.teiid.jdbc.StatementCallback that will be notified of statement events, such as an available row, an exception, or completion. Your calling thread will be free to perform other work. The callback will be executed by an engine processing thread as needed. If your results processing is itself blocking and you want query processing to be concurrent with results processing, then your callback should implement onRow handling in a multi-threaded manner to allow the engine thread to continue.
Non-blocking Prepared Statement Execution
PreparedStatemnt stmt = connection.preparedStatement(sql);
TeiidPreparedStatement tStmt = stmt.unwrap(TeiidPreparedStatement.class);
tStmt.submitExecute(new StatementCallback() {
@Override
public void onRow(Statement s, ResultSet rs) {
//any logic that accesses the current row ...
System.out.println(rs.getString(1));
}
@Override
public void onException(Statement s, Exception e) throws Exception {
s.close();
}
@Override
public void onComplete(Statement s) throws Exception {
s.close();
}, new RequestOptions()
});
The non-blocking logic is limited to statement execution only. Other JDBC operations, such as connection creation or batched executions do not yet have non-blocking options.
If you access forward positions in the onRow method (calling next, isLast, isAfterLast, absolute), they may not yet be valid and a org.teiid.jdbc.AsynchPositioningException will be thrown. That exception is recoverable if caught or can be avoided by calling TeiidResultSet.available() to determine if your desired positioning will be valid.
Continuous Execution
The RequestOptions object may be used to specify a special type of continuous asynch execution via the continuous or setContinuous methods. In continuous mode the statement will be continuously re-executed. This is intended for consuming real-time or other data streams processed through a SQL plan. A continuous query will only terminate on an error or when the statement is explicitly closed. The SQL for a continuous query is no different than any other statement. Care should be taken to ensure that retrievals from non-continuous sources is appropriately cached for reuse, such as by using materialized views or session scoped temp tables. A continuous query must return a result set, must be executed with a forward-only resultset, and cannot be used in the scope of a transaction. Since resource consumptions is expected to be different in a continuous plan, it does not count against the server max active plan limit. Typically custom sources will be used to provide data streams. See the Developer's Guide, in particular the section on ReusableExecutions for more.
When the client wishes to end the continuous query, the Statement.close() or Statement.cancel() method should be called. Typically your callback will close whenever it no long needs to process results.
See also the ContinuousStatementCallback for use as the StatementCallback for additional methods related to continuous processing.